[−][src]Crate smol

A small and fast async runtime.

Executors

There are three executors that poll futures:

Thread-local executor for tasks created by Task::local().
Work-stealing executor for tasks created by Task::spawn().
Blocking executor for tasks created by Task::blocking(), blocking!, iter(), reader() and writer().

Blocking executor is the only one that spawns threads on its own.

See here for how to run executors on a single thread or on a thread pool.

Reactor

To wait for the next I/O event, the reactor calls epoll on Linux/Android, kqueue on macOS/iOS/BSD, and wepoll on Windows.

The Async type registers I/O handles in the reactor and is able to convert their blocking operations into async operations.

The Timer type registers timers in the reactor that will fire at the chosen points in time.

Running

Function run() simultaneously runs the thread-local executor, runs the work-stealing executor, and polls the reactor for I/O events and timers. At least one thread has to be calling run() in order for futures waiting on I/O and timers to get notified.

If you want a multithreaded runtime, just call run() from multiple threads. See here for an example.

There is also block_on(), which blocks the current thread until a future completes, but it doesn't poll the reactor or run executors. When using block_on(), make sure at least one thread is calling run(), or else I/O and timers will not work!

Blocking tasks run in the background on a dedicated thread pool.

Examples

Connect to a HTTP website, make a GET request, and pipe the response to the standard output:

use futures::prelude::*;
use smol::Async;
use std::net::TcpStream;

fn main() -> std::io::Result<()> {
    smol::run(async {
        let mut stream = Async::<TcpStream>::connect("example.com:80").await?;
        let req = b"GET / HTTP/1.1\r\nHost: example.com\r\nConnection: close\r\n\r\n";
        stream.write_all(req).await?;

        let mut stdout = smol::writer(std::io::stdout());
        futures::io::copy(&stream, &mut stdout).await?;
        Ok(())
    })
}

Look inside the examples directory for more: a web crawler, a Ctrl-C handler, a TCP client/server, a TCP chat client/server, a TLS client/server, an HTTP+TLS client/server, an async-h1 client/server, a hyper client/server, and a WebSocket+TLS client/server.

It's also possible to plug non-async libraries into the runtime: see inotify, timerfd, signal-hook, and uds_windows.

Finally, there's an example showing how to use smol with async-std, tokio, surf, and reqwest.

Macros

blocking

Spawns blocking code onto a thread.

Structs

Async	Async I/O.
Task	A spawned future.
Timer	Fires at the chosen point in time.

Functions

block_on	Blocks on a single future.
iter	Creates a stream that iterates on a thread.
reader	Creates an async reader that runs on a thread.
run	Runs executors and polls the reactor.
writer	Creates an async writer that runs on a thread.